Skip to main content
Table of Contents

gitStream - GitLab Installation (cloud & self-managed)

Use this guide to install and configure gitStream with GitLab (cloud or self-managed), set up a central cm project, run gitStream via GitLab CI, and connect everything to LinearB. Time Required: ~10–…

heather.hazell
Updated by heather.hazell

Use this guide to install and configure gitStream with GitLab (cloud or self-managed), set up a central cm project, run gitStream via GitLab CI, and connect everything to LinearB.

Time Required: ~10–20 minutes
Difficulty: Easy–Moderate

Overview

With GitLab, gitStream runs as part of your CI pipeline and executes rules defined in Continuous Merge (.cm) configuration files.

At a high level you will:

  1. Designate a GitLab user that will run gitStream automations.
  2. Create a cm project with a gitstream.cm rules file.
  3. Add a GitLab CI pipeline that runs the gitStream rules engine.
  4. Connect gitStream to your GitLab integration in LinearB.

Before you begin

Prerequisites

  • GitLab (cloud or self-managed).
  • A GitLab runner v15 or higher with ability to run apk package commands.
  • Log in or create a LinearB account and be ready to connect gitStream using a GitLab integration.
  • Allowed network connection between the executors and the following IPs:
    • 13.56.203.235
    • 54.151.81.98

Understanding IP allowlisting

When GitLab allowlisting is enabled, both the gitStream service IPs and your CI runner IPs may need to be allowed. Using self-hosted runners with static IPs can simplify this setup.

IP allowlisting & runners
gitStream runs inside your GitLab CI runners (executors). To work correctly, those runners must be able to make outbound (egress) connections to:

  • 13.56.203.235
  • 54.151.81.98

If your organization uses firewalls or egress control, ensure these IPs are allowed from the runner network.

Step 1 – Designate a gitStream user account

Choose the account that will execute automations

gitStream automation rules are executed on behalf of the user account configured when you connect gitStream to your GitLab instance. This account must have the appropriate permissions to the relevant repositories.

Requirements:

  • The account must have the Maintainer or Owner role for the relevant repos.

Recommendations:

  • Use a dedicated service account with a meaningful identifier that includes gitstream (case-insensitive), such as gitStream-cm.
  • You can use a personal account, but all automations will then be executed under that user and may affect LinearB metrics attribution.

Make sure to use this account when authorizing GitLab in LinearB.

Step 2 – Create a cm project & configuration file

2.1 – Create the cm project
  1. In GitLab, create a new project named cm in the same group or a parent group of the target repositories.
  2. This project is the central place for group-level gitStream rules and the gitStream pipeline.
2.2 – Add a gitstream.cm configuration file

In the cm project’s default branch (usually main or master):

  1. Create a file in the root of the repo named gitstream.cm (the name can vary but must end with .cm).
  2. Define your automations in that file using YAML + gitStream syntax.

Configuration file locations

  • Group-level rules: place .cm files in the root of the cm repository.
  • Repo-level rules: place .cm files under a .cm directory within individual repositories.
Example configuration (aligned with the official GitLab installation page) 
# -*- mode: yaml -*-

          # This example configuration provides basic automations to get started with gitStream.

          # View the gitStream quickstart for more examples.

          manifest:

            version: 1.0

          

          automations:

            # Use LinearB's AI service to review the changes

            linearb_ai_review:

              if:

                - {{ not pr.draft }}

                - {{ not is.bot }}

              run:

                - action: code-review@v1

                  args:

                    approve_on_LGTM: {{ calc.safe_changes }}

          

            # Use LinearB's AI service to add a description to the PR

            linearb_ai_description:

              if:

                - {{ not pr.draft }}

                - {{ not (is.bot_author or is.bot_branch) }}

              run:

                - action: describe-changes@v1

                  args:

                    concat_mode: append

          

            # Add a label indicating how long it will take to review the PR.

            estimated_time_to_review:

              if:

                - true

              run:

                - action: add-label@v1

                  args:

                    label: "{{ calc.etr }} min review"

                    color: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}

          

            # Inform PR authors when they fail to reference Jira tickets in the PR title or description.

            label_missing_jira_info:

              if:

                - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}

              run:

                - action: add-label@v1

                  args:

                    label: "missing-jira"

                    color: {{ colors.red }}

                - action: add-comment@v1

                  args:

                    comment: |

                      This PR is missing a Jira ticket reference in the title or description.

                      Please add a Jira ticket reference to the title or description of this PR.

          

            # Post a comment that lists the best experts for the files that were modified.

            explain_code_experts:

              if:

                - true

              run:

                - action: explain-code-experts@v1

                  args:

                    gt: 10

          

          calc:

            etr: {{ branch | estimatedReviewTime }}

            safe_changes: {{ is.formatting or is.docs or is.tests or is.image }}

          

          has:

            jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}

            jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}

          

          colors:

            red: 'b60205'

            yellow: 'fbca04'

            green: '0e8a16'

          

          is:

            formatting: {{ source.diff.files | isFormattingChange }}

            docs: {{ files | allDocs }}

            tests: {{ files | allTests }}

            image: {{ files | allImages }}

            bot_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }}

            bot_branch: {{ branch.name | match(list=['renovate/']) | some }}

Important: The triggers and on functionality are not currently supported in GitLab. If you include them in your CM automation files, gitStream will skip the automations entirely.

Step 3 – Create a GitLab pipeline for gitStream

3.0 – Confirm variable access settings in the cm project

In your cm project only, ensure the CI/CD Variables setting “Minimum role to use pipeline variables” is configured to any value other than “No one allowed”. This allows the pipeline in the CM repository to access the necessary variables for gitStream to function properly.

You can find this setting under Settings → CI/CD → Variables in the cm project.

3.1 – GitLab-hosted runners

Create .gitlab-ci.yml in the root of the cm project’s default branch and use the following configuration.

# Code generated by gitStream - DO NOT EDIT

          variables:

            DOCKER_DRIVER: overlay2

            DOCKER_HOST: tcp://docker:2375

            DOCKER_TLS_CERTDIR: ""

          

          stages:

            - gitstream-main

          

          image: docker:latest

          

          services:

            - name: docker:dind

          

          before_script:

            - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

          

          gitstream-job:

            stage: gitstream-main

            only:

              variables:

                - $GITSTREAM_MAIN_JOB

            except:

              variables:

                - $GITSTREAM_BLOCK_MERGE

            script:

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - docker pull gitstream/rules-engine:latest

              - |

                docker run -v $CI_PROJECT_DIR/gitstream:/code \

                -e HEAD_REF=$head_ref \

                -e BASE_REF=$base_ref \

                -e CLIENT_PAYLOAD="$client_payload" \

                -e RULES_RESOLVER_URL=$resolver_url \

                -e RULES_RESOLVER_TOKEN=$resolver_token \

                -e DEBUG_MODE=true  gitstream/rules-engine:latest

Choose your runner type

3.2 – Self-managed runners (shell executors)

First, register the runner with a tag, then use that tag in the cm/.gitlab-ci.yml file.

# Code generated by gitStream - DO NOT EDIT

          stages:

            - gitstream-main

          image: docker:latest

          services:

            - docker:dind

          before_script:

            - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

          

          gitstream-job:

            stage: gitstream-main

            tags:

              - REGISTERED-TAG

            only:

              variables:

                - $GITSTREAM_MAIN_JOB

            except:

              variables:

                - $GITSTREAM_BLOCK_MERGE

            script:

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - docker pull gitstream/rules-engine:latest

              - |

                docker run -v $CI_PROJECT_DIR/gitstream:/code \

                -e HEAD_REF=$head_ref \

                -e BASE_REF=$base_ref \

                -e CLIENT_PAYLOAD="$client_payload" \

                -e RULES_RESOLVER_URL=$resolver_url \

                -e RULES_RESOLVER_TOKEN=$resolver_token \

                -e DEBUG_MODE=true  gitstream/rules-engine:latest
3.3 – Self-managed runners (Kubernetes executors)

Ensure your runner configuration (for example config.toml) includes privileged mode. 

[runners.kubernetes]

          privileged = true

Then use the Kubernetes CI template below with your runner tag.

# Code generated by gitStream - DO NOT EDIT

          variables:

            DOCKER_DRIVER: overlay2

            DOCKER_HOST: tcp://docker:2375

            DOCKER_TLS_CERTDIR: ""

          stages:

            - gitstream-main

          

          image: docker:latest

          services:

            - name: docker:dind

              command: ["--mtu=1450", "--tls=false"]

          before_script:

            - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

          

          gitstream-job:

            stage: gitstream-main

            tags:

              - REGISTERED-TAG

            only:

              variables:

                - $GITSTREAM_MAIN_JOB

            except:

              variables:

                - $GITSTREAM_BLOCK_MERGE

            script:

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - docker pull gitstream/rules-engine:latest

              - |

                docker run -v $CI_PROJECT_DIR/gitstream:/code \

                -e HEAD_REF=$head_ref \

                -e BASE_REF=$base_ref \

                -e CLIENT_PAYLOAD="$client_payload" \

                -e RULES_RESOLVER_URL=$resolver_url \

                -e RULES_RESOLVER_TOKEN=$resolver_token \

                -e DEBUG_MODE=true  gitstream/rules-engine:latest
3.4 – Configuring the image location (optional)

By default, gitStream pulls the rules engine image from DockerHub each time it is invoked. You can mirror the image to your own registry and update the docker pull line in cm/.gitlab-ci.yml for faster build times and reduced bandwidth usage. 

script:

          - ...

          - docker pull YOUR-REGISTRY-URL/gitstream/rules-engine:latest

Step 4 – Connect gitStream in LinearB

Connect gitStream to your GitLab integration
  1. Log in to LinearB as your designated gitStream user (Step 1).
  2. Navigate to Settings → Git.
  3. Locate your GitLab integration.
  4. Click Connect gitStream.
  5. Follow the prompts to authorize GitLab and confirm the connection.

Verify

Checklist to confirm gitStream is working
  • In LinearB:
    • GitLab shows as connected.
    • gitStream is connected to the GitLab integration.
  • In GitLab:
    • The cm project exists with:
      • A gitstream.cm file in the root.
      • A .gitlab-ci.yml file in the root.
    • Your runners are online and available.
  • Open or update a Merge Request in a target repo and confirm:
    • The gitStream job runs in the cm project.
    • Labels, comments, or approvals appear according to your .cm rules.

Troubleshooting

Problem Possible cause How to fix
No gitStream pipeline runs on MR activity .gitlab-ci.yml missing/misconfigured; variables access blocked; runner offline
  • Confirm .gitlab-ci.yml exists in the cm repo root on the default branch.
  • Ensure the Minimum role to use pipeline variables setting is not set to No one allowed in the cm project.
  • Confirm your runner is registered and available.
Pipeline runs but no automations execute No matching rules or invalid syntax in gitstream.cm Start with the example configuration above, then layer in additional conditions and actions.
Errors about IP allowlists or denied API calls Service IPs or runner IPs not allowlisted Add the gitStream service IPs and ensure runner egress IPs are allowed.
Automations silently skipped triggers / on used in CM files Remove triggers and on blocks from GitLab CM files.

FAQs

Do I need a cm project?
Yes. The recommended GitLab pattern is a central cm project for group-level rules and the gitStream pipeline.

Can I have different rules per repository?
Yes. Group-level rules live in the cm project root. Repo-specific rules can be added under a .cm directory inside individual repositories.

Does gitStream modify my code?
No. gitStream reads code and metadata and updates Merge Request state (comments, labels, approvals) based on your automations.

✅ You’ve installed gitStream for GitLab and connected it to LinearB.

Next steps

How did we do?

gitStream - GitHub Server Installation (Custom App)

gitStream - Managed Mode (Essentials Plan)

Contact